添加 REST Hook 触发器

在 Platform UI 中，使用设置、输入设计器和 API 配置选项卡来设置您的 REST Hook 触发器。

先决条件

• 您的应用支持 REST Hooks，即可以通过 REST API 操作的 webhook 订阅。
• 存在一个端点，用于设置和删除 hook 订阅，允许 Zapier 发送 Subscribe 和 Unsubscribe API 请求，每个活跃的 Zap 都会使用一个唯一的订阅 URL，即 bundle.targetUrl。
• 存在一个单独的端点，返回预期会触发用户 Zap 的样本项列表。这对于私有应用是可选的，但对于公开应用是必需的。
• 如果您的 webhook 订阅会过期，请确保订阅端点返回一个包含 ISO8601 日期格式的 expiration_date 属性。平台会在过期日期后自动尝试重新订阅。

1. 添加触发器设置

1. 在 Zapier 的 Platform UI 中，打开 Triggers 选项卡，然后选择 Add Trigger。

2. 在设置页面，指定以下内容：

   • Key：此触发器的唯一标识符，用于 Zapier 内部引用。此项不会显示给用户，且保存后无法编辑。
   • Name：此触发器的用户友好名称，通常以形容词（如 New 或 Updated）开头，后跟触发器在您的应用中监视的项名称。标题格式的名称会显示在 Zap 编辑器和 Zapier 应用目录的营销页面上。
   • Noun：一个描述此触发器监视内容的单个名词，由 Zapier 用于自动生成 Zap 中的文本。
   • Description：一个纯文本句子，描述触发器的工作原理以及何时使用。会显示在 Zap 编辑器和 Zapier 应用目录的营销页面上，并以 "Triggers when" 开头。
   • Visibility in Editor：一个选项，用于选择此触发器何时显示。默认选择 Shown。如果此触发器不应显示给用户，请选择 Hidden。通常在触发器尚未准备好用于集成时，或用于为 动态下拉菜单 字段提供支持的轮询触发器时，选择 Hidden。
   • Directions：仅用于静态 webhook，用于描述如何以及在何处复制-粘贴静态 webhook URL 以在您的应用中使用。除此情况外，Directions 不会显示给用户。静态 webhook 在公开集成中不允许使用。

3. 单击 Save and continue 按钮。

2. 完成输入设计器

在 Input Designer 页面，添加用户 输入字段，这些字段是您的 API 用于监视触发项所必需的。

触发器输入字段允许用户输入过滤器、标签和其他详细信息，以筛选端点上的新数据或更新数据。

如果此触发器的端点不需要任何输入数据，则可以继续。

3. 设置 API 配置

在 API Configuration 页面，选择 REST Hook 作为触发器类型，并完成每个部分。

REST Hook 触发器在 Zap 编辑器中标记为 Instant。

订阅

此请求（通常为 POST 请求），会在用户激活以该 REST Hook 触发器开头的 Zap 时执行。这是 Zap 通过订阅请求通知您的 API（通过 webhook），以接收后续所有带有给定参数的触发事件。

订阅请求仅在 Zap 首次启用时，或在活跃的 Zap 被暂停然后取消暂停时才会发出。请注意，发布新草稿并不总是涉及暂停/取消暂停。只有在需要新触发器订阅时，才会发出新订阅请求。例如，如果仅重新映射操作步骤字段（从现有触发器数据），这不会更改触发器本身作为数据源，因此在发布草稿时不会发出新订阅请求。

单击 Show Options 下拉菜单，以向请求正文或 HTTP 标头添加您的 API 所需的用于成功订阅的数据。请确保这里的键与您的 API 期望的键匹配。

Zapier 在发出此请求时会包含一个 targetUrl。您需要存储 targetUrl（通常在数据库中），并通常将其与一个 ID 关联起来。然后，在响应中返回该 ID 回 Zapier，以便稍后用于退订。

您的应用的事件系统会在应用中发生事件时，确定哪些存储的订阅应该被调用，并发布到相应的存储 targetUrl。

webhook URL 可以通过 {{bundle.targetUrl}} 访问。

例如，对于 GitLab 的 API，url 被用作包含 webhook URL 的 {{bundle.targetUrl}} 值的键，用于发送数据。

如果您需要自定义订阅请求，请选择 Switch to Code Mode，并编写自定义 JavaScript 代码来处理 API 调用和响应解析。

建议成功的订阅响应返回 201 状态码。响应返回的数据应包括稍后用于退订请求的任何数据。此数据将存储在 bundle.subscribeData 中。

退订

此请求（通常为 DELETE 请求），是 Zapier 通知您的 API 它不再监听触发事件的方式，例如当 Zap 被停用或删除时。如果您的 API 在 Zap 退订后继续发布通知有效负载，您可能会收到 Zapier 的 410 响应。

单击 Show Options 下拉菜单，以向请求正文或 HTTP 标头添加您的 API 所需的用于成功退订的数据。请确保这里的键与您的 API 期望的键匹配。Zapier 在发送退订请求时，可以引用在订阅请求期间从您的 API 返回并存储在 bundle.subscribeData 中的数据。

如果 REST Hook 触发器缺少订阅或退订端点，它会向用户显示为 [Static Webhook]。静态 webhook 在公开集成中不被支持，但如果集成打算保持私有，则可以使用。

执行列表

此请求（通常为 GET 请求），用于在 Zap 编辑器中收集样本数据，通常在 Zap 激活前使用。这将在用户测试触发器并将字段映射到 Zap 的后续步骤时，用于获取样本数据。尽管可选，但不定义执行列表会给用户带来次优体验，并且对于公开应用是必需的。

最常见的是，对您的 API 的端点发出 GET 请求，该端点会提供与通过 webhook 传递的触发事件数据具有相同架构的响应。

返回的响应数据必须是一个数组，即使数组只包含一个对象。它必须与通过 webhook 传递的触发事件数据具有完全相同的架构，否则，在 Zap 的后续步骤中从此样本映射的字段会在实际运行时出错。

执行

执行函数会在您的应用每次向 Zapier 传递通知有效负载时被调用。使用自定义代码解析 webhook 有效负载并按需修改它，然后将其作为触发器数据返回给 Zap。

执行函数返回的数据必须是一个数组。默认情况下，Zapier 会包含 return [bundle.cleanedRequest]，以将 webhook 中的数据作为数组返回。如果数据需要转换，或包含多个对象，您可以添加自定义代码来解析 bundle.cleanedRequest 中的响应数据，将其转换为对象数组。

如果您的 webhook 已经提供一个数组，您可以删除包装数组并简单地 return bundle.cleanedRequest。

如果出于架构原因，您的 webhook 会接收一些不应触发 Zap 的数据，请在执行函数中添加代码，在这些情况下返回一个空数组，这样 Zap 就不会运行。

对于通过 REST Hook 发送到 Zapier 的数据，大多数请求都会成功并返回 200 状态码以及一些请求跟踪数据。这表示 Zapier 已接受数据，但如果提供的数据结构意外，Zap 中仍可能发生错误。

向 REST Hook 触发器发送数据的最佳实践

• 注意 Zapier 的 速率限制。
• 如果您的应用收到 410 响应，表示该 webhook 订阅不再活跃，您应该停止向它发送数据。
• 如果您的应用从 Zapier 收到反复的 4xx 或 5xx 错误（超出那些错误类型），您可以自行处理。您可能选择稍后重试，或停止发送数据并停用 hook。
• 如果您的应用出于任何原因停用了 hook，您可以选择性地向 Zapier 发送反向退订调用。这可以让用户在您的应用中管理他们的订阅，或允许您在用户删除帐户或撤销凭证后进行清理。请求应采用 DELETE <target_url> 的形式，其中 target_url 是创建订阅时提供的唯一目标 URL。这将在 Zapier 中暂停 Zap。

完成所有端点配置后，单击 Save API Request & Continue。

4. 测试您的 API 请求

要测试 REST Hook 触发器，在编辑器中构建一个 Zap。

5. 定义您的输出

按照 指南 定义样本数据和输出字段。

视频教程

您可以参考此视频，了解 REST Hook 触发器：